:- module(fcompile).
:- export fcompile_body / 3.
:- export fcompile_body / 2.
:- export fcompile / 2.
:- export fcompile / 1.
:- comment(summary, "Generate platform independent object files").
:- comment(desc, html("The fcompile library is used to generate object files from \nECLiPSe source files.  \n<P>\nAn object file has suffix 'eco', and is a platform independent object\nformat which can be loaded into other sessions of ECLiPSe, much as an\nECLiPSe source file. The may however not be portable between different\nversions of ECLiPSe.\n")).
:- comment(fcompile / 1, [summary : "Generates a byte-form object file from the ECLiPSe source File.", args : ["File" : "Name of source file (Atom or string)"], amode : fcompile(++), see_also : [fcompile / 2], desc : html("  <P>Same as <TT>fcompile/2</TT> with all options set to their default\n     values: the object file is placed in the current working directory,\n     byte format is generated, non-verbose, and fcompile tries to\n     compile the program first.</P>")]).
:- comment(fcompile / 2, [summary : "Generates a object file from the ECLiPSe source File with specified options.", args : ["File" : "Name of source file (Atom or string)", "Options" : "List of valid options and their values"], see_also : [fcompile / 1], amode : fcompile(++, ++), eg : "   fcompile(my_prog, []).   % equivalent to fcompile(my_prog)\n\n   fcompile(my_prog, [format:text, outdir:'../']).\n   % generate the object file in text format, and place it in the parent dir\n", desc : html("<P>\n   Compiles the specified Prolog source file and generates an object file\n   with the same base name as the source file but with suffix <TT>.eco</TT>.\n   Object files can be loaded by the built-in predicates <TT>use_module/1</TT>,\n   <TT>lib/1</TT>, <TT>compile/1</TT> and <TT>ensure_loaded/1</TT>, and also\n   with the eclipse -b command-line option.\n</P><P>\n   File must be instantiated to a legitimate specification for an existing\n   file except for the suffix, which may be omitted. Options is a list of\n   Option:Value pairs where Option and value can be:\n</P>\n<DL>\n   <DT>compile: YesOrNo\n\n       <DD> YesOrNo is either the  atom yes or no. For 'yes', fcompile will\n       try to first compile File (checking that it has not already been\n       compiled first).  This is usually what is required, as it ensures\n       that File can be properly read to generate the object file. The\n       default is 'yes'.\n\n   <DT>format: ByteOrText\n\n      <DD>ByteOrText is either the atom <TT>byte</TT> or <TT>text</TT>.  If 'text', the\n      object file will be in a textual format.  If 'byte', the object file\n      will be in a binary format which is larger, but will load faster\n      and is not human readable. The default is byte.\n\n   <DT>outdir: OutputDirectory\n\n       <DD> OutputDirectory is the directory where the generated object\n       file will be placed. It can be an atom or a string. The default is\n       the current working directory.\n\n   <DT>verbose: YesOrNo\n\n       <DD> YesOrNo is either the  atom yes or no. For 'yes', fcompile will\n       report in detail the predicates it is dumping out. This is probably\n       only needed for debugging fcompile, to trace its progress. The default\n       is 'no'.\n</DL><P>\n   The predicate will look for File with a `source' suffix (i.e. no\n   suffix, <TT>.ecl</TT> or <TT>.pl</TT>), compile the file by calling compile, and\n   generate an object form of the source file with suffix <TT>.eco</TT>.\n   The user should use <TT>include/1</TT> directives to include all files that are\n   in the same module as the master file, and <TT>use_module/1</TT> directives for\n   files that define a different module. Files mentioned in include\n   directives will not need to be fcompiled separately for their object\n   form.\n</P><P>\n   This object form can be loaded into an ECLiPSe session even on a\n   different operating system/hardware platform from the one on which\n   it was generated.  However, the object format may change incompatibly\n   between different releases of ECLiPSe.\n</P><P>\n   The fcompile library does not need to be loaded in order to load the object\n   file.  The built-in predicates <TT>ensure_loaded/1</TT>, <TT>use_module/1</TT>\n   and <TT>lib/1,2</TT> will try to load an object file in preference to a\n   source file, if both are present.  The compile built-ins on the\n   other hand will prefer source files, unless the <TT>.eco</TT>\n   suffix is explicitly given.\n</P><P>\n   It is recommended that object files always contain proper modules.\n   If an object file contains module-free code, then loading it into\n   an existing module that already has code can cause conflicts with\n   auxiliary predicates (e.g. from <TT>do/2</TT> loop constructs).\n</P><P>\n   <EM>Restrictions:</EM>\n<UL>\n     <LI>macro definitions should be quoted using \n     <TT>no_macro_expansion/1</TT>, e.g.\n     <PRE>\n         :- local macro(no_macro_expansion(maxint), 9999).\n     </PRE>\n\n     <LI>directives in the module should not change the state \n         of compiled code.\n\n     <LI>big integer constants between -2^63 and -2^31 and between\n     \t2^31 and 2^63 should not appear directly in the source, and\n\twill provoke a warning because the generated object code will\n\tnot be portable between 32 and 64 bit machines.\n</UL>\n</P>")]).
:- comment(fcompile_body / 3, hidden).
:- comment(fcompile_body / 2, hidden).